Copyright: Copyright (c) 1995 Okino Computer Graphics, Inc.


Wavefront OBJ Geometry Import Converter

This geometry import converter reads in Wavefront 'OBJ' format files in their entirety, including vertex, normal and texture coordinates, as well as grouping and smoothing information. The converter is also unique in its ability to import Wavefront NURBS models via the OBJ file format - the only other known import converters to read full Wavefront NURBS models are Alias PowerAnimator and Wavefront. However, more and more NURBS modeling programs are now beginning to export NURBS models via the Wavefront OBJ file format, such as Rhino and Alias.

The converter is a complete and accurate implementation of the Wavefront OBJ file format, including the parsing of all attributes in a Wavefront material (.mtl) file. Many companies which sell 3D models provide their datasets in the OBJ file format, so you can use this converter to read in these data files and be guaranteed nice rendered results.

The converter will also read material definitions from a Wavefront material file (typically which has a file extension '.mtl') if the material file is referenced within the Wavefront geometry file (typically which has a file extension '.obj') using the 'mtllib' keyword. If one or more Wavefront material files are listed on a single line then all will be read into memory for possible reference by the geometry file.

The converter first reads the entire file into memory; this includes the vertex, normal and texture coordinate lists, their indice lists, all group names, material names and texture names, and the smoothing groups assigned to each polygon. Next, the converter computes new vertex normals for polygons that don't have any normals and that have a non-zero smoothing group assigned to them. If no smoothing groups are found then the converter optionally creates smoothed vertex normals based on the angle between abutting polygon faces. As a last step, the polygonal data is separated into separate objects based on a user-chosen criteria.

NOTES:

1.	If any texture map names are found in the .obj file ('usemap <map_name>', which is the old-style Wavefront texture reference method) and the 'Use Material Name' drop-down list box option is enabled then texture definitions will be automatically created for these texture names and will be assigned to their corresponding surfaces. NOTE:: you can distinguish these textured surfaces because the texture map name is appended to the end of the surface name (the surface and texture names are separated by three underscores '_').

2.	All texture map information is read in from a material file. The supported mapping parameters include:map_Ka, map_Kd, map_Ks, map_d, map_refl and map_bump. All sub-option parameters are also read into memory and mapped to equivalent internal database values: -o, -s, -mm and -bm.

3.	If one or more group names are found on a 'g' line, then they are appended all together to form the group name used internally (ie: 'g all airplane tail_fin').

Dialog Box Options:

The following information explains the various options on the dialog box:

Compute normals using assigned smoothing groups

If this checkbox is enabled then new vertex normals will be computed for a polygon if it does not have any vertex normals already and it has been assigned a non-zero smoothing group number. Two abutting polygons will appear to be smooth only if they share common vertices.

Compute averaged normals

If this checkbox is enabled then new vertex normals will be computed for a polygon if it does not have any vertex normals already, and it does not have a smoothing group assigned to it or the 'Compute normals using assigned smoothing groups' checkbox is disabled. The smoothing criterion is based on the angle between abutting polygons; common smoothed vertex normals will be computed if the angle between their geometric surfaces normals is less than the angle specified on the dialog box (which defaults to 30 degrees).

Flip Model so that Y Axis is Up

If this checkbox is enabled then the model will be reoriented so that the Up axis of the model will be aligned with the positive Y axis (which is used by the converter) instead of the positive Z axis as used by some Wavefront files, or as used by models exported from the Rhino modeler.

Make imported material names unique

If this checkbox is enabled (which is the default) then the import converter will make all new material names unique if there are conflicts upon import. For example, if a model currently resides in memory which uses a surface definition (a material) named redbricks and another Wavefront file is read into memory which also contains the material called redbricks then this second reference will be renamed to redbricks#2 once it has been imported into the scene. The benefit of enabling this option is that two imported files will use completely different material/surface definitions, even if the imported files are read in from the same Wavefront .obj file.

If this checkbox is disabled then any imported file which makes references to materials that are already loaded into the scene will use those materials/surfaces rather than create new unique ones. Disabling this option is useful if multiple Wavefront .obj files share a common Wavefront .mtl file (ie: all imported .obj files should only share one set of material/surface definitions in memory).

Import Trimmed NURBS Patches (From Alias, Rhino, etc.)

This Wavefront import converter has the unique and high-end feature of being able to import complete trimmed NURBS model descriptions from a Wavefront OBJ file. If this checkbox is enabled (check-marked) then trimmed NURBS models will be imported. If disabled (un-checkmarked) then all NURBS models will be ignored.

Read Wavefront.mtl material files

If this checkbox is enabled then the import converter will read in and parse any Wavefront .mtl material files referenced within the .obj file (via the keyword usemtl). If this option is disabled then no material files will be read.

Read texture information from .mtl material files

If this checkbox is enabled then the texture mapping information found in a Wavefront .mtl material file will be read into memory and stored along with the new surface definitions created. If this checkbox is disabled then no texture mapping information will be read in from the material file.

Color scaling: Ambient, diffuse, specular

These three values allow the intensity of the ambient (Ka), diffuse (Kd) and specular (Ks) colors found within a Wavefront .mtl material file to be scaled brighter or darker. Many 3d programs export Wavefront material colors overly saturated (ie: ambient = 100% white, diffuse = 100% white) whereas many 3d rendering programs would like to see these values at about 30% to 50% of full saturation. For example, if the Ka value is set to 0.3 and the ambient material color is specified as (1 1 1) = 100% white, then the ambient color will be read into the database as (0.3, 0.3, 0.3) = 30% white.

Report statistics about the geometry file

If this checkbox is enabled then statistics about the geometry file will be reported once it has been read in and processed.

Print warning messages

If this checkbox is enabled then warning messages will be reported as the file is read in. Warnings include unrecognized input and options, out-of-range texture coordinates and out-of-range index values.

Source for the Surface Name

This drop-down list box specifies which method the converter is to use to assign a surface definition to each polygon. Automatic assignment of surfaces to the polygons will save you a lot of time and headache.

Use material name, else group names if no materials found

The surface name will be taken from the material name assigned to each polygon. If no materials are found in the file then the surface name will be taken from the group name assigned to each polygon. ace name will be taken from the material name assigned to each polygon. If no group names are assigned to the polygons then the surface name will be taken from the object name assigned to each polygon. If no material, group or object name is assigned then the "default" surface will be used.

This is the default method.

Use material names found in file, else "default" surface if no materials

This will use the material name associated with each polygon as the surface name. If no material name is assigned then the "default" surface will be used.

Use group names found in file, else "default" surface if no groups

This will use the group name associated with each polygon as the surface name. If no group name is assigned then the "default" surface will be used.

Use object names found in file, else "default" surface if no objects

This will use the object name associated with each polygon as the surface name. If no object name is assigned then the "default" surface will be used.

Method for Splitting Polygons

into different objects. If your 3D scene is going to have many different objects in it then it is recommended that the OBJ not be split up. However, if you want to modify each individual part in the OBJ file then you will want to split it up into different objects.

Don't split into different objects

This option prevents the OBJ file from being split up into separate objects.

Split by object name

This will split the polygonal geometry according to the object name assigned to each polygon.

Objects are assigned to polygons in the OBJ file by preceding them with a line like: 'o <object_name> ... <object_name>'.

Split by group name

This will split the polygonal geometry according to the group name assigned to each polygon. It is the most logical method for splitting the geometry since the group names are usually assigned on an object-name basis by the person who designed the 3D model.

Groups are assigned to polygons in the OBJ file by preceding them with a line like: 'g <group_name1> ... <group_nameN>'.

Split by material name

This will split the polygonal geometry according to the material name assigned to each polygon. You may want to use this method if no group names are provided in the file or if it makes more sense to split by material name than by group name (for example, the object might have 300 odd group names but 20 carefully chosen material names).

Materials are assigned to polygons in the OBJ file by preceding them with a line like: 'usemtl <material_name>'.

Split by texture map name

This will split the polygonal geometry according to the texture map name assigned to each polygon. In most cases you will not use this method.

Texture map names are assigned to polygons in the OBJ file by preceding them with a line like: 'usemap <texture_map_name>'.

Split by smoothing group numbers

This will split the polygonal geometry according to the smoothing group number assigned to each polygon. Since smoothed polygons are usually clustered together as one sub-object this method can be used to accurately extract sub-objects from the polygonal data. However, it will probably create many more new objects than would the 'Split by group name' method above.

Smoothing groups are assigned to polygons in the OBJ file by preceding them with a line like: 's <smoothing_number>'.


NURB Patch Display Options

This dialog allows the NURB patches imported from the Wavefront OBJ file to be displayed either as  a triangulated mesh (Yes) or as simple bounding boxes (No).

Overview

Wavefront OBJ file format has the added option of being able to store NURB patch data, complete with trimming curve information. This information can be exported from such programs as Alias PowerAnimator or Robert McNeels Rhino. NURB patches are mathematical expressions that describe smooth, curved 3D surfaces. NURB patches cannot, however, be rendered directly without first being converted into polygons. The process of converting NURB patches into a mesh of polygons is called tesselation. For a small number of patches this tesselation process is fast, but for complex Wavefront OBJ files with thousands of patches it can take several minutes to tesselate an entire model. It is for this reason that this dialog box has been provided.

If you press Yes then the program will immediately begin to tesselate the NURB patches into polygons. This may take anywhere from a few seconds to several minutes. Once tesselated the resulting polygon mesh can be rendered or it can be exported to other 3D file formats.

If you press No then the NURB patches will be displayed as bounding boxes rather than the true NURB surface. This option prevents the NURB patches from being tesselated right away. Rather, the slow tesselation process will  only be performed later when the patches are to be rendered or if they are to be exported to another file format.

Please note, however, that the tesselation process only has to be performed once. Thereafter, the polygon mesh will be saved to disk along with the original NURB patch data (but only for Okino`s .bdf file format).

Which Option Should I Select?

Click Yes if:

•	You want to see what the imported NURB patches look like in their approximated polygon mesh format.

•	If you want to enable Shaded Mode within Okinos NuGraf or PolyTrans software (the OpenGL shading mode requires polygons).

•	The number of imported NURB patches is not huge.

Click No if:

•	You only desire to convert the imported NURB patches to another NURB-based file format, such as SoftImage. In this case there is no need to create the tesselated polygon mesh since the NURB data is being directly converted to another file format.

•	If the number of imported NURB patches is very large and/or complex.

•	You do not wish to wait for the imported NURB patches to be tesselated. In this case the NURB patches will only be tesselated prior to rendering or to re-export.

NOTES:

1.	If you do not want this dialog to be displayed every time a Wavefront OBJ file is imported then un-checkmark the Show this dialog box option. To re-enable this dialog box, press the Reset button on the main Wavefront OBJ import dialog box

2.	Once the NURB data has been imported you can enable/disable the bounding box mode by selecting the Display NURB patches as boxes menu item in the Views menu of Okinos PolyTrans and NuGraf software. The default mode is specified by the General Startup Preferences dialog box also contained within these programs.